/*
 * Copyright 2016-2018 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.creactiviti.piper.core.task;

import com.creactiviti.piper.core.error.Errorable;
import com.creactiviti.piper.core.error.Prioritizable;
import com.creactiviti.piper.core.error.Progressable;
import com.creactiviti.piper.core.error.Retryable;

import java.util.Date;

/**
 * <p>Extends the {@link PipelineTask} interface to add execution semantics to 
 * the task.</p> 
 * 
 * <p>{@link TaskExecution} instances capture the life cycle of a single 
 * execution of a task. By single execution is meant that the task
 * goes through the following states:</p> 
 * 
 * <ol>
 *   <li><code>CREATED</code></li>
 *   <li><code>STARTED</code></li>
 *   <li><code>COMPLETED</code> or <code>FAILED</code> or <code>CANCELLED</code></li>
 * </ol>
 * 
 * @author Arik Cohen
 * @since May 8, 2017
 */
public interface TaskExecution extends PipelineTask, Errorable, Retryable, Prioritizable, Progressable {

  /**
   * Get the unique id of the task instance.
   * 
   * @return String the id
   */
  String getId ();
  
  /**
   * Get the id of the parent task, if this
   * is a sub-task.
   * 
   * @return String the id of the parent task.
   */
  String getParentId ();
  
  /**
   * Get the id of the job for which this task 
   * belongs to.
   * 
   * @return String the id of the job
   */
  String getJobId ();
  
  /**
   * Get the current status of this task.
   * 
   * @return The status of the task.
   */
  TaskStatus getStatus ();
  
  /**
   * Get the result output generated by the task
   * handler which executed this task.
   * 
   * @return Object the output of the task
   */
  Object getOutput ();
  
  /**
   * Get the time when this task instance 
   * was created.
   * 
   * @return Date
   */
  Date getCreateTime ();

  /**
   * Get the time when this task instance 
   * was started.
   * 
   * @return Date
   */
  Date getStartTime ();
  
  /**
   * Return the time when this task instance 
   * ended (CANCELLED, FAILED, COMPLETED)
   * 
   * @return Date
   */
  Date getEndTime ();
  
  /**
   * Returns the total time in ms for this task
   * to execute (excluding wait time of the task
   * in transit). i.e. actual execution time on 
   * a worker node.
   * 
   * @return long
   */
  long getExecutionTime ();
  
}
